home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 June / Macworld (1999-06).dmg / Shareware World / Info / For Developers / MacZoop2.0.sea / MacZoop2.0 / Required Classes / ZTimer.h < prev    next >
Text File  |  1999-02-11  |  3KB  |  115 lines
  1. /*************************************************************************************************
  2. *
  3. *
  4. *            MacZoop - "the framework for the rest of us"         
  5. *
  6. *
  7. *
  8. *            ZTimer.h            -- simple timer object
  9. *
  10. *
  11. *
  12. *
  13. *
  14. *            © 1998, Graham Cox
  15. *
  16. *
  17. *
  18. *
  19. *************************************************************************************************/
  20.  
  21.  
  22. #pragma once
  23.  
  24. #ifndef __ZTIMER__
  25. #define    __ZTIMER__
  26.  
  27.  
  28. #include "ZComrade.h"
  29. #include "ZObjectArray.h"
  30.  
  31. class    ZTimer;
  32. class    ZCommander;
  33.  
  34. typedef ZObjectList ZTimerQueue;
  35.  
  36. #define    kOneSecond            60
  37.  
  38. // class definition:
  39.  
  40. class    ZTimer    : public    ZComrade
  41. {
  42. protected:
  43.     long            id;
  44.     unsigned long    interval;
  45.     unsigned long    lastTicks;
  46.     ZCommander*        wOwner;
  47.     Boolean            oneShot;
  48.     
  49. public:
  50.     
  51.     ZTimer( unsigned long tRate = kOneSecond, long anID = 0, ZCommander* owner = NULL, Boolean isOneShot = FALSE );
  52.     
  53.     inline long            GetID() { return id; };
  54.     inline ZCommander*    GetOwner() { return wOwner; };
  55.     inline long            GetElapsedTime() { return TickCount() - lastTicks; };
  56.     
  57.     virtual void        Do();
  58. };
  59.  
  60. // timer message if no window associated:
  61.  
  62. enum
  63. {
  64.     kTimerMsgTimerTripped    = 'ttrp'
  65. };
  66.  
  67. // timer message data is the id of the timer
  68.  
  69.  
  70. // timers are usually set up using the following global functions:
  71.  
  72.  
  73. ZTimer*        SetTimer( ZCommander* aCmdr = NULL, long id = 0, unsigned long interval = kOneSecond, Boolean isOneShot = FALSE );
  74. void        KillTimer( ZCommander* aCmdr, long id );
  75. void        KillAllTimers( ZCommander* aCmdr );
  76.  
  77. /*
  78.  
  79. ZTimer has a very similar functionality to the Windows timer concept- windows programmers
  80. will see the similarity immediately. However, this is more flexible if lower resolution.
  81.  
  82. You can associate one or more timers with a commander object, and that timer will call your
  83. commander's DoTimer() method at the interval you specify, within the resolution and frequency
  84. of the current application.
  85.  
  86. To set up a timer, call SetTimer, passing your commander reference, an interval and an ID. Your
  87. commander's DoTimer method will be called at the interval you specify. When you want to stop
  88. a timer, call KillTimer. When your commander is destroyed, you should call KillAllTimers, but
  89. the standard ZCommander destructor will do this.
  90.  
  91. All active timers are stored in a global queue, and this queue is managed by ZApplication.
  92. n.b. this queue is not directly accessible to your application or classes.
  93.  
  94. Timers have a resolution of 1 tick, but you may get called less often if your main loop is
  95. slower than this, or your app is in the background. Your window is Focussed before the
  96. DoTimer call is made, for your convenience. Another way to use a timer if you don't want it
  97. to be associated with a window, is to pass NULL as the window reference and become a listener
  98. of the timer, in which case you'll get kTimerMsgTimerTripped messages.
  99.  
  100. If you pass 0 for the ID, one will be assigned dynamically.
  101.  
  102. Note that unlike Windows, you can have as many timers as you want.
  103.  
  104. Timers are synchronous with your application main loop. If your application is busy and does
  105. not call the main loop, or a menu is down, the timers are not triggered. Timers are triggered
  106. if your lengthy procs use a progress bar however, since that calls back to the main loop. The
  107. rate in this case depends partly on how often your progress bar is updated so will probably
  108. drop for timers that are set to a rapid rate.
  109.  
  110.  
  111. */
  112.  
  113.  
  114.  
  115. #endif